feat: living-docs add-on - state file, rendered blocks, deterministic doc checks - #8
Merged
Conversation
… doc checks A RepoKit-scaffolded ops repo showed that prose doc-sync rules do not hold across sessions and models: runbook/README drift, superseded content accreting, contradictory counts, and formatting churn. Make the fix structural instead: - docs/STATE.json holds each volatile shared fact once (value + as_of + note); README.md and docs/**/*.md render facts via marker-delimited state blocks. - scripts/check-docs.ps1 (pwsh 7) rewrites blocks (-Update) and enforces: blocks match the state file, no stale/future as_of, no superseded-content markers in the runbook, one table-separator style. docs.yml runs it in CI at the Core tier - enforcement is the point, especially in private repos. - Packaged as an opt-in /new-repo add-on (templates/addons/living-docs/core), a third axis orthogonal to type and tier; add-ons only add files. - New standard docs: living-docs.md (pattern + adopt-in-existing-repo recipe) and doc-style.md (deterministic formatting rules for all repos); both checklists gain doc-consistency steps. - smoke_test_living_docs.ps1 proves the enforcement, negative tests included; validate.yml runs it on ubuntu-latest. See ADR-0006 for the decision record and rejected alternatives (hand-written HTML runbook, generated HTML, prose-only rules, YAML state file). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Docs that track live operational state drift when the only defence is prose rules: a RepoKit-scaffolded ops repo hit runbook/README drift (15 runbook-only commits despite an explicit same-commit rule), superseded content accreting under "superseded by v2" annotations, contradictory counts, and per-session formatting churn. This PR makes doc consistency structural: volatile facts live once in
docs/STATE.json, docs render them via marker-delimited state blocks, and a deterministic pwsh 7check-docs.ps1(+ Core-tierdocs.ymlCI) enforces it - block drift, staleas_ofdates, superseded-content markers, and table-style violations all fail the check, independent of which model or session edits the docs.Shipped as an opt-in
/new-repoadd-on (a third axis orthogonal to type and tier - private repos stay light), plus two newrepo-standarddocs (living-docs.md,doc-style.md), doc-consistency steps in both checklists, andsmoke_test_living_docs.ps1proving the enforcement in CI with negative tests. Decision record: ADR-0006.Checklist
feat: ...).CHANGELOG.mdupdated under## [Unreleased]if user-visible.python scripts/*.py; both pwsh smoke tests; e2e scaffold with and without the add-on).docs/adr/for any notable decision (ADR-0006).🤖 Generated with Claude Code